home *** CD-ROM | disk | FTP | other *** search
/ Aminet 24 / Aminet 24 (1998)(GTI - Schatztruhe)[!][Apr 1998].iso / Aminet / dev / c / AmiVoGL_MDEV.lha / docs / vogl.doc < prev    next >
Text File  |  1994-04-19  |  51KB  |  2,047 lines
  1.  
  2.  
  3.  
  4. VOGL(3)                C LIBRARY FUNCTIONS                VOGL(3)
  5.  
  6.  
  7.  
  8. NAME
  9.      VOGL - A very ordinary GL Library.
  10.  
  11.  
  12. DESCRIPTION
  13.      VOGL is a library of C routines which try to  allow  a  pro-
  14.      grammer  to  write  programs  which can be moved to machines
  15.      which have the Silicon Graphics GL library on  them.  It  is
  16.      based  entirely  on  the  VOGLE  graphics  library, and as a
  17.      result  can  handle  circles,  curves,  arcs,  patches,  and
  18.      polygons in a device independent fashion. Simple hidden line
  19.      removal is also available via polygon backfacing. Access  to
  20.      hardware  text  and  double buffering of drawings depends on
  21.      the driver.  There is also a FORTRAN  interface  but  as  it
  22.      goes  through  the  C routines FORTRAN users are warned that
  23.      arrays are in row-column order in C. Both the  long  FORTRAN
  24.      names  and  the shortened six character names are supported.
  25.      People interested in using  software  text  should  see  the
  26.      hershey library, HERSHEY(3).
  27.  
  28.      Some routines are only available in  VOGL.  If  you  include
  29.      them  in  programs  it  is  advisable to put #ifdef VOGL ...
  30.      #endif around them. The constant VOGL is defined whenever  a
  31.      VOGL header file is included.
  32.  
  33.      It should be noted that there are a number of routines  that
  34.      take the type Angle for some of their parameters. All angles
  35.      specified this way are actually Integer Tenths  Of  Degrees.
  36.      (Don't ask!)
  37.  
  38.  
  39.   Include files.
  40.      There are two include files provided with vogl:  vogl.h  and
  41.      vodevice.h.   The  file  vogl.h has the type definitions and
  42.      function interfaces, ideally it is included where you  would
  43.      include  gl.h on an SGI. The file vodevice.h has the devices
  44.      in it, and it is included where you would  include  device.h
  45.      on an SGI.
  46.  
  47.  
  48.      The following is a brief summary of the VOGL subroutines.
  49.  
  50.   Device routines.
  51.      vinit(device)
  52.           Tell VOGL what the device is. This routine needs to  be
  53.           called  if  the environment variable VDEVICE isn't set,
  54.           or if the value in VDEVICE is not to be used.
  55.  
  56.                Fortran:
  57.                     subroutine vinit(device, len)
  58.                     character *(*) device
  59.                     integer len
  60.  
  61.  
  62.  
  63. VOGL 1.0            Last change: 6 June 1991                    1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. VOGL(3)                C LIBRARY FUNCTIONS                VOGL(3)
  71.  
  72.  
  73.  
  74.                C:
  75.                     vinit(device);
  76.                     char     *device;
  77.  
  78.                Note 1 :- Current available devices are:
  79.                         tek - tektronix 4010 and compatibles
  80.                         hpgl - HP Graphics language and compatibles
  81.                         dxy - roland DXY plotter language
  82.                         postscript - postscript devices
  83.                         ppostscript - postscript devices (portrait mode)
  84.                         sun - Sun workstations running sunview
  85.                         X11 - X windows (SUN's Openwindows etc etc)
  86.                         decX11 - the decstation (old) window manager
  87.                               This is only included in case you need it.
  88.                         apollo - Apollo workstations
  89.                         NeXT   - NeXTStep
  90.                         hercules - IBM PC hercules graphics card
  91.                         cga - IBM PC cga graphics card
  92.                         ega - IBM PC ega graphics card
  93.                         vga - IBM PC vga graphics card
  94.                         sigma - IBM PC sigma graphics card.
  95.  
  96.                         Sun, X11, decX11, apollo, hercules, cga
  97.                         and ega support double buffering.
  98.  
  99.  
  100.                Note 2 :- If device is a NULL or a null string the value
  101.                     of the environment variable "VDEVICE" is taken as the
  102.                     device type to be opened.
  103.  
  104.                Note 3 :- after init it is wise to explicitly
  105.                     clear the screen.
  106.  
  107.                e.g.: in C
  108.                     color(BLACK);
  109.                     clear();
  110.  
  111.                or    in Fortran
  112.                     call color(BLACK)
  113.                     call clear
  114.  
  115.  
  116.      ginit()
  117.           Open the graphics device and do the  basic  initialisa-
  118.           tion. This routine is marked for obsolescence. The rou-
  119.           tine winopen (see below) should be used instead.
  120.  
  121.                Fortran:
  122.                     subroutine ginit
  123.  
  124.                C:
  125.                     ginit()
  126.  
  127.  
  128.  
  129. VOGL 1.0            Last change: 6 June 1991                    2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. VOGL(3)                C LIBRARY FUNCTIONS                VOGL(3)
  137.  
  138.  
  139.  
  140.      winopen(title)
  141.           Open the graphics device and do the  basic  initialisa-
  142.           tion. This routine should be used instead of ginit.
  143.  
  144.                Fortran:
  145.                     subroutine winopen(title, len)
  146.                     character*(*) title
  147.                     integer len
  148.  
  149.                C:
  150.                     winopen(title)
  151.                          char *title;
  152.  
  153.  
  154.      gexit()
  155.           Reset the window/terminal (must be the last  VOGL  rou-
  156.           tine called)
  157.  
  158.                Fortran:
  159.                     subroutine gexit
  160.  
  161.                C:
  162.                     gexit()
  163.  
  164.  
  165.      voutput(path)
  166.           Redirect output from *next*  ginit  to  file  given  by
  167.           path. This routine only applies to devices drivers that
  168.           write to stdout e.g. postscript and hpgl.
  169.  
  170.                Fortran:
  171.                     subroutine voutput(path, len)
  172.                     character*(*) path
  173.                     integer len
  174.  
  175.                C:
  176.                     voutput(path)
  177.                          char *path;
  178.  
  179.  
  180.      vnewdev(device)
  181.           Reinitialize VOGL to use a new device without  changing
  182.           attributes,  viewport  etc.   (eg.  window and viewport
  183.           specifications)
  184.  
  185.                Fortran:
  186.                     subroutine vnewdev(device, len)
  187.                     character *(*) device
  188.                     integer len
  189.  
  190.                C:
  191.                     vnewdev(device)
  192.  
  193.  
  194.  
  195. VOGL 1.0            Last change: 6 June 1991                    3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. VOGL(3)                C LIBRARY FUNCTIONS                VOGL(3)
  203.  
  204.  
  205.  
  206.                          char *device;
  207.  
  208.     getplanes()
  209.           Returns the number of bit planes (or  color
  210.           planes)  for  a particular device. The number of colors
  211.           displayable by the device is then 2**(nplanes-1)
  212.  
  213.                Fortran:
  214.                     integer function  getplanes()
  215.                C:
  216.                     long
  217.                     getplanes()
  218.  
  219.  
  220.   Routines For Setting Up Windows.
  221.      Some devices are basically window orientated - like  sunview
  222.      and X11. You can give VOGL some information about the window
  223.      that it will use with these routines.  These can  make  your
  224.      code  very  device  dependent.  Both routines take arguments
  225.      which are in device space. (0, 0) is the  bottom  left  hand
  226.      corner  in  device  space. To have any effect these routines
  227.      must be called before ginit or winopen.  For the X11 device,
  228.      an  entry  may  be  made in your .Xdefaults file of the form
  229.      vogl.Geometry  =150x500+550+50  (where  you   specify   your
  230.      geometry as you please).
  231.  
  232.      prefposition(x1, y1, x2, y2)
  233.           Specify the preferred position of the window opened  by
  234.           the *next* winopen.
  235.  
  236.                Fortran:
  237.                     subroutine prefposition(x1, y1, x2, y2)
  238.                     integer x1, y1, x2, y2
  239.  
  240.                C:
  241.                     prefposition(x1, y1, x2, y2)
  242.                          long x1, y1, x2, y2
  243.  
  244.  
  245.      prefsize(width, height)
  246.           Specify the preferred width and height  of  the  window
  247.           opened by the *next* winopen.
  248.  
  249.                Fortran:
  250.                     subroutine prefsize(width, height)
  251.                     integer width, height
  252.  
  253.                C:
  254.                     prefsize(width, height)
  255.                          long width, height;
  256.  
  257.  
  258.  
  259.  
  260.  
  261. VOGL 1.0            Last change: 6 June 1991                    4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. VOGL(3)                C LIBRARY FUNCTIONS                VOGL(3)
  269.  
  270.  
  271.  
  272.      reshapeviewport
  273.           This is occasionally used in Iris GL if a R